SixPack is subject to the "SixPack Open Source License"
Development Notes
This is the initial developer release of SixPack, and as such there is much that is not finished, including the documentation. This document serves as a "sketch" for documenting SixPack and will be expanded as development continues. If there are areas that you feel need attention, please let me know, so that, if anything, I can put it on my TODO list.
For instructions on basic usage of the SixPack editor, please see the accompanying "Read Me" file. For licensing details, please consult the "License" file.
SixPack is open source and I welcome your fixes, enhancements, etc. If you wish to contribute to SixPack, please note the following;
-Currently SixPack is being developed in REALbasic 2.1a17 (Standard).
-If your code contribution is very specific (like a few lines or sub or function) send it to me as text in an email.
-If your contribution is larger, you can send REALbasic class, module, or project files (binhex it).
-Document your code.
-All code must work on 68k/PPC.
-No XCMDs/XFCNs, Toolbox calls, or Plug-ins (if you are really set on using one of these, contact me and talk me into it).
-Feature requests are ok, but new code is better.
Future enhancements/wish list; exception handling, find and replace, printing, save via FTP, syntax highlighting in source view, DTD support, some sort of XSL support (though IMHO XSL is, at present, a giant mess) and non-recursive versions of the parser/source output methods.
Questions, comments, rants & raves to sixpack@trafficstudio.com
Enjoy,
Geoff Strom
simple/CHAOS
Highlights of the XML Classes
In order to use the SixPack parser in your own applications you will need the following (all of which are in the "XML Classes" folder inside the SixPack project file):
Classes
-CXMLObject
-CXMLFragment
-CXMLAssocStringArray
-CXMLAssocObjectArray
Modules
-XMLParserModule
There are two basic methods for use, ParseXML and MakeXMLSource
Example:
dim doc as CXMLObject
dim s as string
doc=ParseXML("<root>hello world!</root>")
// doc is now a DOM that represents the XML that was parsed
s=MakeXMLSource(doc) // let's make the DOM back into source
// now s="<root>hello world!</root>"
XML Class Details
CXMLObject methods
.init(type as string)
possible values for type; "root", "element", "comment", "pi", "cdata", "chardata"
The CXMLObject class is the heart of the parser and is the device by which a simple DOM is implemented (the DOM implementation used in SixPack does not meet W3's proposal for DOM Level 1, but for our purposes it works just fine).
The CXMLObject has the following properties, which depending on how it is initialized may be nil pointers:
name as string(used in "root" and "element" types only)
type as string (must be one of these values: "root", "element", "comment", "pi", "cdata", "chardata")
value as string (used in "comment", "pi", "cdata", "chardata" types only)
uid as integer (every CXMLObject has a unique ID number)
attributes as CXMLAssocStringArray (used in "root" and "element" types only, for all
other types this will be nil)
contents as CXMLAssocObjectArray (used in "root" and "element" types only, for all other types this will be nil)
index as CXMLAssocObjectArray (used in "root" type only, for all other types this will be nil)
Nearly every operation you undertake on a DOM will be accomplished primarily through the root's index property (which gives you access to every object in the DOM tree). Please see the associative array discussion below for traversal details. You can also walk through the DOM tree by way of an objects "contents" array.
CXMLFragment
The CXMLFragment class is only used internally by the parser and has no public functions.
CXMLAssocStringArray methods
set(key as string,value as string)
get(key as string) as string
remove(key as string)
getkey(index as integer) as string
keycount() as integer
CXMLAssocObjectArray methods
set(key as string,value as CXMLObject)
get(key as string) as CXMLObject
remove(key as string)
getkey(index as integer) as string
keycount() as integer
The two array classes behave exactly the same, the only difference is that one provides an associative array for string values and one is an associative array for CXMLObjects. Both are 1 based arrays and cannot be operated on by REALbasic's built-in array methods.
While you would typically use the set, get, & remove methods to operate on the array members, there are many times when we don't know what the key is. Fortunately, we can determine the key by use of the getkey method and in conjunction with the keycount method we can traverse these arrays quite easily.
Example:
// let's pretend that AssocArray was already dimmed and populated as a CXMLAssocStringArray
dim i as integer
dim s as string
for i=1 to AssocArray.keycount
s = s + AssocArray.get(AssocArray.getkey(i))
next
XMLParserModule methods
ParseXML(source as string) as CXMLObject
source must be well formed XML, returns a "root" CXMLObject
example:
dim doc as CXMLObject
doc=ParseXML("<root>hello world!</root>")
MakeXMLSource(tag as CXMLObject) as string
tag must be an "element" or "root" CXMLObject, returns well formed XML
MakeXMLObjectListBox(doc as CXMLObject, box as ListBox)
doc must be a "root" CXMLObject, box must be a two column (100%,0%) hierarchical ListBox, use of this method also requires that the following 16x16 pixel pictures be available in the project file: element, comment, pi, cdata, text
In order to display all DOM elements, the ListBox must also call MakeXMLObjectListBox during its "Expand" event
GetParent(doc as CXMLObject, searchID as string) as CXMLObject
doc must be a "root" CXMLObject, searchID is the uid of the CXMLObject whose parent object you want to find, returns an "element" or "root" CXMLObject if successful or nil if the search fails
DeleteObject(doc as CXMLObject, targetID as string) as boolean
doc must be a "root" CXMLObject, targetID is the uid of the CXMLObject you want to delete, returns true if successful or false if the deletion fails
AddObject(doc as CXMLObject, NewObj as CXMLObject, targetID as string) as integer
doc must be a "root" CXMLObject, NewObj can be any CXMLObject except "root", targetID is the uid of the object you wish to add NewObj to, returns the uid of the object that NewObj was actually added to (as integer), if the add fails it returns -1
note: even though the targetID is specified, you can only add objects to "element" and "root" type objects, so if the targetID is for a non-element type object (like "comment") AddObject will find targetID's parent and add the NewObj to it instead
Highlights of the Support Classes
CBetterEditField
This is an improved EditField subclass that adds support for single level undo/redo and select all. To use it simply put the class in your project and change the "super" of any editfields you use to CBetterEditField.
Once a CBetterEditField based editfield regains focus (after losing it) the undo cache is cleared.
You must have the following menuitems in your project: EditUndo, EditCut, EditCopy, EditPaste, EditClear, EditSelectAll.
In the future, this class will likely be enhanced to add support for multi-level undo.
Note
The SixPack editor does make use of a 3rd party class for some interface elements. The class is CPictureButton written by Bjorn Eiriksson and it is a protected class.
